home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / mint / shells / init9akp.zoo / init.doc next >
Text File  |  1991-11-04  |  13KB  |  324 lines
  1. This file is not an "official" part of MiNT, but please distribute it
  2. with init.prg.
  3.  
  4. This document describes the version of the "init" shell released
  5. 11/4/91 by Allan Pratt.
  6.  
  7. -----------------------------------------------------------------------
  8. init.prg: by Allan Pratt and Eric Smith
  9.  
  10. Here is a sample shell that can be used as init.prg for MiNT (if you like
  11. it; there's nothing special about this shell, and any other non-GEM program
  12. could be used, or gem.prg if you want GEM to start right away). This shell
  13. is useful mainly for its understanding of job control.
  14.  
  15. When started, init looks in the current directory for the file "init.rc";
  16. if this file is found, the lines in it are read and processed just as if
  17. they had been typed at the keyboard. A prompt is then printed, and lines
  18. are read from the keyboard until an end of file character (^D) is
  19. encountered. Commands on a line may be separated by the ";" character (in
  20. which case they are executed one after another), the "&" character (in
  21. which case they are executed concurrently), or by the "|" character (in
  22. which case they are executed concurrently with the standard output of the
  23. first command connected to the standard input of the second command). Any
  24. line starting with a "#" character is treated as a comment, and ignored.
  25.  
  26. External commands are searched for using the environment variable PATH,
  27. which should consist of directories separated by commas. See the sample
  28. init.rc for an example. Arguments are passed to external commands using the
  29. Atari extended argument passing convention.
  30.  
  31. I/O redirection is supported for external commands; to redirect the output
  32. of a command to a file, use "> file"; to append to a file use ">> file";
  33. and to redirect input from a file use "< file".  In addition, use ">& file"
  34. or ">>& file" to redirect both stdout and stderr to file, and "2> file" or
  35. "2>> file" to redirect just stderr.  "prog args 2> err > out" will redirect
  36. stderr to "err" and stdout to "out."
  37.  
  38. Command-line Arguments
  39. ============ =========
  40.  
  41.   -v        Causes all commands to be echoed to the screen before they're
  42.         executed.  See VERBOSITY.
  43.  
  44.   -s        Causes batch files to be aborted if a command in the batch 
  45.         file exits with nonzero $STATUS.  See BATCH_EXIT.
  46.  
  47.   -c args ...    All args after -c are collected into a line, and that line
  48.         is executed by the shell. Then the shell exits with that
  49.         command's $STATUS code.
  50.  
  51.  
  52. Variables
  53. =========
  54.  
  55. Variables are set with setenv, and are referenced by prefixing their names
  56. with a "$", e.g.:
  57.  
  58.    echo $PATH
  59.  
  60. will echo the value of the environment variable PATH. The name may be
  61. enclosed in parentheses or braces; thus
  62.  
  63.    setenv FOO foo
  64.    echo $(FOO)bar ${FOO}bar 
  65.  
  66. will echo "foobar foobar". If there are no
  67. parentheses or braces, the name of the environment variable ends with the
  68. first character not in the set [A-Za-z0-9_?*], so "echo $FOO\bar" yields
  69. "foo\bar" and "echo $FOO*" does not yield files matching "foo*" but rather
  70. the value of the variable 'FOO*'.
  71.  
  72. Typing "setenv" with no arguments will show the values of all environment
  73. variables.
  74.  
  75. The following variables have special meaning to the shell:
  76.  
  77.     $PATH: as mentioned above, is used to find programs.  Setting this
  78.     causes an automatic "rehash" (see below).
  79.  
  80.     $PROMPT: printed before each line of input in an interactive shell.
  81.  
  82.     $BATCH_EXIT: the value of this variable should be a number. When
  83.     nonzero, batch files (and even the shell itself) will exit when any
  84.     command returns a nonzero exit code.
  85.  
  86.     $VERBOSITY: when nonzero, all commands are displayed on the screen
  87.     after being alias-expanded, wildcard-expanded, and
  88.     variable-substituted, but before being executed.
  89.  
  90.     $NOTIFY: when nonzero, a message will be printed on your screen as
  91.     soon as a background job exits, rather than waiting until the next
  92.     time the shell prompt is printed.
  93.  
  94. In addition, the following things can be used like environment variables,
  95. but they are not truly in your environment:
  96.  
  97.     $CWD: yields your current working directory.
  98.  
  99.     $STATUS: yields the exit code of the last command or batch file.
  100.     (the exit code of a batch file is the exit code of the last command
  101.     executed from that batch file.)
  102.  
  103. If you use $ for variable-substitution on the command line and there is no
  104. variable with the name you give, an error message is printed and the
  105. command is not run.
  106.  
  107. Wildcards
  108. =========
  109.  
  110. It is possible to refer to a group of files with similar names by means of
  111. special characters ("wildcards"). For example, the pattern "*.c" means "all
  112. files that have the extension .c". Thus, if the current directory contains
  113. the files "foo", "foo.c", "bar.c", and "bar.doc", the command
  114.  
  115.     echo *.c
  116.  
  117. would be exactly equivalent to
  118.  
  119.     echo foo.c bar.c
  120.  
  121. and
  122.  
  123.     echo *c
  124.  
  125. would be the same as
  126.  
  127.     echo foo.c bar.c bar.doc
  128.  
  129. (Note that the files appear in their "true" order on the disk, not necessarily
  130. in alphabetical order).
  131.  
  132. The following wildcards are supported:
  133.  
  134. *:    matches any sequence of 0 or more characters
  135. ?:    matches any 1 character
  136. [...]:  matches one character inside the brackets; if two characters are
  137.     seperated by a minus sign ('-') then all characters between those
  138.     two are also matched
  139.  
  140. Examples:
  141.  
  142. [ad-gz]*    matches all files beginning with 'a', 'd', 'e', 'f', 'g', or
  143.         'z' (read as "(a, or d through g, or z) followed by anything").
  144.  
  145. *.*        matches all files containing a period. Note the difference
  146.         from some wildcard matching, in which '*.*' matches ALL files.
  147.  
  148. a*.[ch]        matches all files starting with 'a' and having an extension
  149.         of '.c' or '.h'.
  150.  
  151. If you have any wildcards in a command line, and none of them actually
  152. matches any files, an error message is printed and the command is not run.
  153.  
  154. Batch Files
  155. ===========
  156.  
  157. Init commands may be placed in a file with a ".bat" extension; typing the
  158. filename (with or without the ".bat" extension) will then run those
  159. commands.
  160.  
  161. Arguments to batch files are accessed in a way similar to environment
  162. variables: $1 yields the first argument to the batch file, $2 the second,
  163. and so on.  $0 yields the name of the batch file itself, $* yields all
  164. arguments from $1 on, $? yields the number of arguments, and the built-in
  165. command 'shift' shifts $3 to $2, $2 to $1, and so on, and decrements $?. 
  166. 'shift' leaves $0 alone.  Example of a simple batch file which executes the
  167. command named in its first argument, giving it the string "fixed_args" as
  168. its first argument and the rest of the batch-file command line as the rest
  169. of its args:
  170.  
  171.     echo This is batch file $0, which will execute the command $1.
  172.     setenv cmdHOLD $1
  173.     shift
  174.     $cmdHOLD fixed_args $*
  175.  
  176. Batch file arguments do nest, but each one is executed by the same shell,
  177. with the same environment and so on, so they can affect the global shell
  178. state (i.e. current directory, environment, aliases, etc.).  This is a lose
  179. and should be re-done.  In the meantime, if you want to execute a batch
  180. file in its own shell, use "init -c batch_file_name batch_file_args ..."
  181.  
  182. [Note to shell hackers: the ability to use $? relies on dollar substitution
  183. being done before wildcard substitution, because ? is a wildcard character.
  184. Also, the ability to use $? (and $STATUS) is useless without an "if"
  185. command.]
  186.  
  187. Version note: arguments to batch files are new as of 2/91.
  188.  
  189. Grubby details department: if a string starting with a digit gets to dollar
  190. substitution, atoi is called on it and that's what you get. The
  191. substitution for $1one is the first argument to the batch file, not
  192. getenv("1one").  If there is no Nth argument you get an error message.
  193.  
  194. Builtin Commands
  195. ================
  196.  
  197. The following commands are built in:
  198.  
  199. alias [string [command]]
  200.     With no arguments, prints a list of all aliases.
  201.     With one argument, shows what command the given string is aliased to.
  202.     With two or more arguments, the first argument ("string") becomes an
  203.     alias for the command consisting of all the other arguments. After this,
  204.     typing "string" is the same as typing that command.
  205.     Example:
  206.     alias c d:\bin\gcc.ttp -O -c
  207.     c